package com.core.gwt.place.client;

/**
 * Represents a modal interaction within an activity - e.g. in-place editing -
 * which must either complete or be canceled before the user can move away from
 * the activity or start another modal interaction.<br>
 * <br>
 * A mode is entered by calling
 * {@link ModeManager#enterMode(ActivityMode)}.
 * 

 * 
 */
public interface Mode {
	/**
	 * The handler of the activity mode which must be notified when the mode
	 * completes.
	 */
	public static interface Handler {
		/**
		 * Call this method when the user exists the activity mode to signal
		 * that the mode is completed.
		 */
		void onExit();
	}

	/**
	 * Called when the activity mode is being canceled because the user is
	 * navigating away from the activity or starting another modal interaction.
	 */
	void cancel();

	/**
	 * Called when the activity mode is entered. Implementing classes must
	 * display the mode's UI and call {@link Handler#onExit()} when the mode
	 * completes.
	 * 
	 * @param handler
	 *            the handler of the activity mode which must be notified when
	 *            the mode completes
	 */
	void enter(Handler handler);

	/**
	 * Called when the user is trying to navigate away from the activity or to
	 * start another modal interaction.
	 * 
	 * @return a message to display to the user, e.g. to warn of unsaved work,
	 *         or null to say nothing
	 */
	String mayCancel();
}
